Guia Prático de Usabilidade — Módulo Seller
Público-alvo: Equipe de Operações e Administradores Protheus
Versão: 1.0
1. Configuração do Schedule (MAIS IMPORTANTE)
A função U_SHSELL05 é a ÚNICA que deve ser configurada no Schedule do Protheus para operação diária automatizada. Ela executa tanto vendas quanto devoluções para a empresa e filial informadas.
Como criar a tarefa no Schedule
- Acesse Configurador (SIGACFG) → Schedule
- Clique em Novo e preencha os campos:
| Campo | Valor |
|---|---|
| Função | U_SHSELL05 |
| Parâmetros | {"01", "22"} |
| Frequência | Diária |
| Horário | 01:00 (madrugada) |
- Salve e ative a tarefa.
Explicação dos parâmetros
// U_SHSELL05 — Execução completa (vendas + devoluções)
// Parâmetros: {"<cEmpAnt>", "<cFilAnt>"}
// Exemplo para empresa 01, filial 22:
{"01", "22"}
- 1º parâmetro: Código da empresa (
"01") - 2º parâmetro: Código da filial (
"22")
Recomendações
- Horário: Madrugada (ex.: 02:00), fora do horário de pico operacional
- Frequência: Diária (após o fechamento do dia anterior)
- A primeira execução fará a carga inicial (veja seção 2); execuções subsequentes serão incrementais (D-1)
2. Configuração da Primeira Carga
A carga inicial carrega o histórico completo dos últimos dias (controlado por ES_SELLMAXD). Siga estes passos:
Passo 1 — Ativar flag de primeira carga
No módulo SIGACFG → Parâmetros (MV), configure para a empresa/filial desejada:
MV_PARAM: ES_SELLFST
Conteúdo: .T.
Passo 2 — Executar U_SHSELL05
Rode a função normalmente (via Schedule ou execução manual — veja seção 4). O sistema carregará os últimos 720 dias de histórico (ou o valor definido em ES_SELLMAXD).
Passo 3 — Verificação automática
Após a execução bem-sucedida, o sistema automaticamente define ES_SELLFST = .F.. Nenhuma intervenção manual é necessária.
Passo 4 — Execuções subsequentes
A partir da segunda execução, o sistema opera em modo incremental (D-1) — carregando apenas os dados do dia anterior.
Atenção: Se precisar recarregar o histórico completo novamente, basta reativar
ES_SELLFST = .T.e executarU_SHSELL05.
3. Funções Individuais do Schedule
Caso precise executar apenas vendas ou apenas devoluções de forma agendada, utilize as funções abaixo. Não é necessário usá-las se U_SHSELL05 já estiver configurada.
U_SHSELL03 — Somente Vendas
// Configuração no Schedule:
Função: U_SHSELL03
Parâmetros: {"01", "22"}
U_SHSELL04 — Somente Devoluções
// Configuração no Schedule:
Função: U_SHSELL04
Parâmetros: {"04", "22"}
4. Execução Manual
Para executar manualmente as funções (por exemplo, para testes ou reprocessamento de datas específicas):
U_SHSELL01 — Vendas manual (com intervalo de datas)
// Sintaxe:
// U_SHSELL01(<cEmpAnt>, <cFilAnt>, <dDataDe>, <dDataAte>, <cTipo>)
// Exemplo: vendas da empresa 01, filial 22, entre 01/07/2025 e 31/07/2025
U_SHSELL01("01", "22", CTOD("01/07/2025"), CTOD("31/07/2025"), "V")
| Parâmetro | Descrição |
|---|---|
cEmpAnt | Código da empresa |
cFilAnt | Código da filial |
dDataDe | Data inicial (formato Date; deixar "" para automático) |
dDataAte | Data final (formato Date; deixar "" para automático) |
cTipo | "V" = Vendas |
U_SHSELL02 — Devoluções manual
// Sintaxe:
// U_SHSELL02(<aParams>)
// Exemplo: devoluções da empresa 01, filial 22, datas automáticas
U_SHSELL02({"01", "22", "", ""})
Parâmetros do array: {cEmpAnt, cFilAnt, dDataDe, dDataAte}
U_SHSELL11 — Auditoria via console
// Sintaxe:
// U_SHSELL11(<dDataIni>, <dDataFim>, <cModo>, <cEmpAnt>, <cFilAnt>)
// Exemplo: auditar todos os registros (modo "A") dos últimos 7 dias
U_SHSELL11(Date() - 7, Date(), "A", "01", "22")
// Exemplo: auditar apenas erros (modo "E")
U_SHSELL11(Date() - 7, Date(), "E")
| Parâmetro | Descrição |
|---|---|
dDataIni | Data inicial do período de auditoria |
dDataFim | Data final do período de auditoria |
cModo | "A" = Todos / "E" = Somente erros |
cEmpAnt | Código da empresa (opcional se omitido) |
cFilAnt | Código da filial (opcional se omitido) |
5. Monitoramento
U_SHSELL12 — Monitor (ZRM)
// Exibe o monitor gráfico colorido com status dos registros
U_SHSELL12()
O monitor exibe os registros com codificação por cores:
| Cor | Significado |
|---|---|
| 🟢 Verde | Sucesso — registro processado sem erros |
| 🟡 Amarelo | Duplicado — registro já existente no CRM (HTTP 409) |
| 🔴 Vermelho | Erro — falha no processamento (verificar conectividade/credenciais) |
U_SHSELL11 — Auditoria rápida dos últimos 7 dias
U_SHSELL11(Date() - 7, Date(), "A")
U_SHSELL13 — Marcar pendências para reprocessamento
// Sintaxe:
// U_SHSELL13(<cAcao>, <aParams>)
// Exemplo: marcar registros pendentes da empresa 01, filial 22
U_SHSELL13("MARK", {"01", "22"})
Use esta função quando houver registros que falharam e precisam ser reenviados na próxima execução agendada.
6. Parâmetros MV de Referência
| MV | Tipo | Valor Padrão | Finalidade |
|---|---|---|---|
ES_SELLFST | Lógico | .F. | Flag de primeira carga. Quando .T., carrega todo o histórico. |
ES_SELLMAXD | Numérico | 720 | Dias máximos de lookback (retrospecto) na carga inicial. |
ES_SELLRETR | Numérico | 3 | Número máximo de tentativas HTTP em caso de falha de rede. |
Como consultar/alterar um MV
// Consultar valor atual
GetMV("ES_SELLFST")
// Alterar valor (requer permissão)
PutMV("ES_SELLFST", .T.)
7. Solução de Problemas (Troubleshooting)
Erro: "variable is not array" no Schedule
Causa: Os parâmetros da tarefa não foram configurados no formato correto de array.
Solução: Verifique se os parâmetros estão entre chaves {}. O formato correto é:
{"01", "22"} ← Correto
01, 22 ← Incorreto
HTTP 409 (Duplicate / Duplicado)
Causa: A nota/venda já existe no CRM.
Ação: Nenhuma. Este é um comportamento normal e esperado. O monitor ZRM exibirá o registro em amarelo. O sistema ignora duplicatas automaticamente.
ORA-00904: invalid identifier
Causa: Campos customizados da ZRM não foram criados no SX3 (dicionário de dados).
Solução: Verifique se todos os campos customizados da tabela ZRM foram devidamente registrados no SIGACFG → SX3. Consulte a documentação técnica de instalação do módulo.
Monitor ZRM exibe linhas VERMELHAS
Causa provável: Falha de conectividade com a API REST ou credenciais inválidas.
Ações:
- Verifique se o endpoint da API REST está acessível a partir do servidor Protheus
- Confira as credenciais configuradas nos parâmetros MV de autenticação
- Execute
U_SHSELL11(Date() - 1, Date(), "E")para ver a mensagem de erro detalhada - Se os registros estavam pendentes por falha temporária de rede, use
U_SHSELL13("MARK", {"01", "22"})para marcá-los e aguarde a próxima execução do Schedule
Execução não carrega dados novos
Causa: Possível flag de primeira carga desativada prematuramente ou período sem movimentação.
Ações:
- Execute
U_SHSELL11(Date() - 3, Date(), "A")para verificar se há registros no período - Confirme que
ES_SELLFSTnão está.F.quando deveria estar.T.(carga inicial) - Verifique se há notas/devoluções no período em questão diretamente no ERP
Resumo Rápido — Comandos Mais Usados
// Agendar (Schedule):
U_SHSELL05 com {"01", "22"}
// Primeira carga:
PutMV("ES_SELLFST", .T.) → executar U_SHSELL05 → automático
// Monitor visual:
U_SHSELL12()
// Auditoria dos últimos 7 dias:
U_SHSELL11(Date() - 7, Date(), "A")
// Reprocessar pendências:
U_SHSELL13("MARK", {"01", "22"})
// Vendas manuais (período específico):
U_SHSELL01("01", "22", CTOD("01/07/2025"), CTOD("31/07/2025"), "V")